\chapter{Norme di documentazione}
Per la stesura dei documenti verra utilizato laTex in particolare nella sua distrubuzione teTex(\href{http://www.tug.org/tetex/}{http://www.tug.org/tetex/}).\\

\section{Layout}
Le formattazioni contenute nel file \texttt{Documenti/Template/model/layout.tex} possono essere modificate solo se strettamente necessarie (e comunque dietro apertura di un issue), questo file contiene le formattazioni generali di tutti i documenti.\\
Vanno considerati allo stesso modo anche gli altri file del modello latex ossia i file contenuti nella cartella \texttt{Documenti/Template/model}.
Il file principale di ogni documento (quello che dà il nome al PDF) e il \textit{diario delle modifiche} vanno modificati solo se necessario e solo entro i termini stabiliti in questo documento.

\section{Modifiche ai documenti}
Le modifiche ai documenti devono sempre essere svolte a seguito di una necessità segnalata sottoforma di issue. In particolare il file principale di ogni documento (quello con lo stesso nome della cartella) può essere modificato solo in due punti:
\begin{enumerate}
\item Nella prima riga nel caso vada aumentato il numero di versione,\\ \texttt{$\backslash$newcommand\{$\backslash$lastversion\}\{0.5\}}. Per le norme sul versionamento rimandiamo alla sezione ``Versionamento''.
\item Nell'elenco dei capitoli per aggiungere o modificare l'inclusione dei capitoli, \texttt{$\backslash$input\{Capitolo1.tex\}}.
\end{enumerate}
Il file \texttt{DiarioModifiche.tex} contiene l'elenco delle principali modifiche apportate al documento. Per tale file sono previste modifiche solo alle righe della tabella (introducendone di nuove), non alla tabella stessa.


\section{Blocchi di codice}
Per evidenziare e rendere facilmente identificabili dei blocchi di codice in un documento essi devono utilizzare un font più piccolo ed essere racchiusi in una tabella con grandezza fissata a 12.2 centimetri. Il blocco di codice dovrà poi essere racchiuso all'interno dei comandi \texttt{$\backslash$begin\{verbatim\}} ed \texttt{$\backslash$end\{verbatim\}}. Tutto ciò che viene scritto all'interno del comando verbatim viene ignorato dal compilatore latex. Le indentazioni nel codice vanno rese con degli spazi. Inoltre se all'interno della tabella è riprodotto un pezzo di codice (parziale) bisogna precedere il codice e farlo seguire da ``\texttt{...}''. Non bisogna preoccuparsi invece di lasciare spazi all'inizio o alla fine del codice, in quanto il comando verbatim si occupa da solo di mantenere degli spazi minimi. Nel sorgente bisogna quindi scrivere:\\
\begin{small}
\begin{tabular}{|p{12.2cm}|}
\hline
\begin{verbatim}
...
\begin{small}
\begin{tabular}{|p{12.2cm}|}
\hline
\begin{verbatim}
...
Esempio di codice
    ...
Finito il bloco verbatim si conclude con
...
\hline
\end{tabular}
\end{small}\\
...
\end{verbatim}\\
\hline
\end{tabular}
\end{small}\\
\\
Nel caso in cui invece una keyword del codice debba essere scritte all'interno di un blocco di testo normale, essa và scritta untilizzando il comando \texttt{$\backslash$texttt\{...\}} e inserendovi la keyword all'interno. attenzione nei blocchi di codice lunghi a spezzare sia le linee che il blocco stesso, in modo da evitare errori di layout.

\section{Andare a Capo}
Per andare a capo vanno usare le $\backslash$$\backslash$ a fine riga e non devono essere precedute da nessun spazio.\\
Non vanno indicate nel caso l'andata a capo sia automantica per esempio dopo il comando \texttt{$\backslash$section\{\}}\\
Ogni paragrafo deve essere terminato con un $\backslash$$\backslash$.\\

\section{Elenchi puntati}
Gli elenchi puntati dovranno contenere le keywork  \textit{item} non dovrà essere presente nessuna spaziatura prima della keyword, dopo la keyword  \textit{item} ci dovrà essere un solo spazio.\\
\begin{small}
\begin{tabular}{|p{12.2cm}|}
\hline
\begin{verbatim}
...
\begin{itemize}
\item primo elenco puntato
\item secondo elenco puntato
\item terzo elenco puntato
\end{itemize}
...
\end{verbatim}\\
\hline
\end{tabular}
\end{small}\\
\\
Nel caso di elenchi puntati innestati, ogni nuovo livello va inserito con un tab di indentazione superiore rispetto al livello precedente:\\
\begin{small}
\begin{tabular}{|p{12.2cm}|}
\hline
\begin{verbatim}
...
\begin{itemize}
\item primo livello
    \begin{itemize}
    \item secondo livello
        \begin{itemize}
        \item terzo livello
        \end{itemize}
    \end{itemize}
\end{itemize}
...
\end{verbatim}\\
\hline
\end{tabular}
\end{small}


\section{Indentazioni di paragrafo}
In automatico vengono effettuate le indentazioni della prima riga dei paragrafi, queste indentazioni automatiche vanno tolte inserendo la \textit{keyword} $\backslash$noindent all'inizio dei paragrafi composti da una solo riga o all'inizio di tabelle nel caso sia all'inizio di un paragrafo\\

\section{Tabelle}
Ogni riga della tabella deve essere composta da:\\
\texttt{testo prima cella \& testo seconda cella$\backslash$$\backslash$\\}
All'inizio e alla fine di ogni cella deve esserci uno spazio, tranne all'inizio della prima cella e alla fine dell'ultima cella tra \& e la cella precedente deve esserci un solo spazio ed anche tra \& e la cella successiva. Ogni riga termina con un $\backslash$$\backslash$. Ogni riga della tabella è separata dalla riga successiva da una linea \texttt{$\backslash$hline} questa istruzione va inserita in una riga vuota senza spazi ne all'inizio ne alla fine:\\
\\
\begin{small}
\begin{tabular}{|p{12.2cm}|}
\hline
\begin{verbatim}
...
0.2 & 2009-01-12 & Michele Tonon &  Aggiunta Norme Documentazione\\
\hline
0.1 & 2009-01-12 & Michele Tonon &  Stesura struttura\\
\hline
...
\end{verbatim}\\
\hline
\end{tabular}
\end{small}\\
\\
\noindent Le tabelle devono avere i campi delle descrizioni di colonna staccati dal resto della tabella. Tra i campi delle descrizioni di colonna(prima riga) e le altre devono essere inserite due istruzioni $\backslash$hline in due nuove linee:\\
\\
\begin{small}
\begin{tabular}{|p{12.2cm}|}
\hline
\begin{verbatim}
...
Versione & Data & Autore & Descrizione\\
\hline
\hline
0.2 & 2009-01-12 & Michele Tonon &  Aggiunta Norme Documentazione\\
...
\end{verbatim}\\
\hline
\end{tabular}
\end{small}\\
\\
\noindent Prima della chiusura della tabella bisogna inserire un altro $\backslash$hline:\\
\\
\begin{small}
\begin{tabular}{|p{12.2cm}|}
\hline
\begin{verbatim}
...
0.1 & 2009-01-12 & Michele Tonon &  Stesura struttura\\
\hline
\end{tabular}
...
\end{verbatim}\\
\hline
\end{tabular}
\end{small}\\
\\
Nelle tabelle il testo non deve mai terminare con un punto, può essere che all'interno del testo ci sia un punto per dividere due frasi, ma non va messo alla fine.

\section{Date}
Tutte le date devono essere indicate nel formato standard ISO 8601:2000 ovvero: YYYY-MM-DD.\\
Esempio: \texttt{2009-01-13}.\\

\section{Linee vuote}
Non va aggiunta nessuna riga vuota prima di \texttt{$\backslash$chapter}. Prima del comando \texttt{$\backslash$section} deve sempre esserci una linea vuota nel sorgente.\\
Alla fine di ogni file non deve essere presente nessuna linea vuota.\\
Nel caso si abbia la necessità di inserire una linea vuota per separare un blocco di testo da un esempio di codice bisogna andare a capo e scrivere nella linea vuota solo \texttt{$\backslash$$\backslash$} in questo modo si forza una linea vuota senza incorrere in un indentazione nella linea successiva.

\section{Lettere accentate}
Grazie all'introduzione del pacchetto \textit{unicode} \texttt{$\backslash$usepackage\{ucs\}} (all'interno del template dei documenti), ogni lettera accentata viene processata correttamente senza bisogno di \textit{escape} (normalmente bisognerebbe scrivere la \texttt{e} accentata così \texttt{$\backslash$\char18 e}). Attenzione con il sistema unicode sono valide solo le lettere accentate delle tastiere italiane ossia non è possibile scrivere \texttt{e\char18}. Nel caso si renda però necessario iniziare una frase con una lettera maiuscola accentata, tale lettera va preceduta dal \textit{backslash} \texttt{$\backslash$} e dal carattere di accento \texttt{\char18} (non dal carattere di apostrofo \texttt{'}). Per esempio per scrivere ``\texttt{\`E importante ...}'' nel sorgente bisogna scrivere ``\texttt{$\backslash$\char18E importante...}''.

\section{Versionamento - Quando incrementare}
Ogni documento deve rispettare strette regole sia nella definizione del \textit{numero di versione}, sia nell'aggiunta dello stesso numero al \textit{diario delle modifiche}. Prima di tutto va detto che la versione di un documento va incrementata solo se necessario, ossia in quei casi in cui sia necessario rendere noto ad altre persone che il documento è stato modificato rispetto alla sua precedente versione. Questo avviene ad esempio nel caso di una nuova release pubblica (pdf) del documento, o nel caso sia necessario che i membri del gruppo prendano visione delle modifiche apportate allo stesso. In definitiva non va incrementato il numero di versione per correzioni e cambiamenti minimali. Va invece incrementato il numero di versione ogni qual volta il documento subisce delle modifiche sostanziali o tali da dover essere rese note agli altri membri del gruppo o al pubblico. Ogni altra modifica va tracciata nelle \textit{revisioni svn}.

\section{Versionamento - Come incrementare}
Il numero di versione nei documenti è costituito da due cifre separate da un punto. Un incremento nella prima cifra indica un cambiamento notevole (l'introduzione di un nuovo capitolo, stravolgimenti nell'ordine dei paragrafi o altro). Un incremento nella seconda cifra indica invece un cambiamento minore (modifiche a un paragrafo, introduzione di un nuovo paragrafo). Ogni qual volta venga incrementata la prima cifra la seconda viene azzerata. Ossia se sono alla versione \textit{0.4} e incremento la prima cifra passo alla \textit{1.0} e non alla \textit{1.4}.

\section{Virgolette}
Per fare le virgolette (doppie o singole) si utilizzano accenti per quelle iniziali e apostrofi per quelli finali. Per le virgolette doppie bisogna scrivere \texttt{\char18\char18Testo''} e si ottiene ``Testo'' per le virgolette singole si scrive \texttt{\char18Testo'} e si ottiene `Testo'.
\href{http://en.wikipedia.org/wiki/Kile}{Kile} in automatico inserisce questi valori per voi da qualsiasi sistema operativo e da qualsiasi tastiera. Quando si preme \texttt{shift+2} per fare le virgolette Kile genera due accenti \texttt{\char18\char18} e quando chiudete le virgolette alla fine del testo genera due apostrofi.